OAuth für Fremdsysteme

Allgemein

Über OAuth 2.0 können Fremdsysteme (z. B. eigene Programme, Schnittstellen anderer Hersteller oder Skripte) die Plattform-Schnittstelle von domizil+ aufrufen, ohne sich wie ein Benutzer anzumelden. Das Fremdsystem holt sich mit einer Client-ID und einem Secret ein zeitlich begrenztes Zugriffstoken (Access-Token) und schickt es bei jedem Aufruf mit.

Jeder OAuth-Client ist an einen Benutzer von domizil+ gebunden. Das Fremdsystem arbeitet mit genau den Rechten dieses Benutzers – legen Sie dafür einen eigenen, technischen Benutzer mit den nötigen Rechten an. Ein Administrator kann nicht hinterlegt werden.

Unterstützt wird das Verfahren Client Credentials (Anmeldung einer Anwendung ohne Benutzerdialog).

Client anlegen

Die Verwaltung finden Sie im Menü Administration → OAuth-Clients. Dafür ist das Recht OAuth-Clients verwalten nötig; Administratoren haben es automatisch.

Feld	Bedeutung
Name	Frei wählbare Bezeichnung, z. B. der Name des Fremdsystems
Client-ID	Kennung, mit der sich das Fremdsystem meldet. Erlaubt sind Kleinbuchstaben, Ziffern sowie -, _ und .; sie muss eindeutig sein
Benutzer	Benutzer, dessen Rechte für das Fremdsystem gelten (kein Administrator)
Gültig bis	Optional: ab diesem Tag stellt der Server keine Tokens mehr aus
Aktiv	Ein deaktivierter Client wird sofort gesperrt, auch für bereits ausgestellte Tokens
Scopes	Welche Bereiche das Fremdsystem verwenden darf (siehe unten)

Scopes

Scope	Haken im Dialog	Erlaubt
framework.read	Plattform-Daten lesen	Schema, Abfrage und Prüfung der Plattform-Dienste
framework.write	Plattform-Daten schreiben	Speichern über die Plattform-Dienste
dms.read	DMS-Daten lesen	Schema, Abfrage und Prüfung der DMS-Dienste
dms.write	DMS-Daten schreiben	Speichern über die DMS-Dienste
om.read	OM-Daten lesen	Schema, Abfrage und Prüfung der Dienste der Objektverwaltung
om.write	OM-Daten schreiben	Speichern über die Dienste der Objektverwaltung

Unabhängig von den Scopes sind für OAuth-Clients gesperrt: Anmeldung und Sitzungen, die Verwaltung von OAuth-Clients, Benutzern, Gruppen und Rechten (auch die Benutzer-Zusatzdaten der Objektverwaltung), die Konfiguration der Objektverwaltung, freie SQL-Abfragen sowie die Server-Verwaltung. Schnittstellen des Rechnungswesens sind über OAuth nicht erreichbar.

Secret erzeugen

Im Detail eines Clients erzeugt Neues Secret ein neues Secret. Es wird nur einmal angezeigt – kopieren Sie es sofort und hinterlegen Sie es im Fremdsystem. In domizil+ wird nur ein Prüfwert gespeichert; das Secret selbst kann später nicht mehr angezeigt werden.

Ein Client kann mehrere gültige Secrets haben. So wechseln Sie ein Secret ohne Unterbrechung: neues Secret erzeugen, im Fremdsystem eintragen, danach das alte mit Secret löschen entfernen. Die Spalte Zuletzt verwendet zeigt, ob ein Secret noch benutzt wird.

Token holen

Das Fremdsystem fordert das Token am Server an:

POST https://<server>/<pfad>/framework/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client-id>&client_secret=<secret>

Optional schränkt scope=framework.read dms.read das Token auf einen Teil der erlaubten Scopes ein. Client-ID und Secret können statt im Formular auch per HTTP-Basic-Anmeldung (Authorization: Basic …) übergeben werden.

Beispiel mit PowerShell:

$token = Invoke-RestMethod -Method Post -Uri "https://server/DPlus/framework/v1/oauth/token" -Body @{
    grant_type    = "client_credentials"
    client_id     = "mein-fremdsystem"
    client_secret = "<secret>"
}
$token.access_token

Antwort:

{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600, "scope": "framework.read" }

Das Token gilt 60 Minuten. Danach holt das Fremdsystem einfach ein neues.

Schnittstelle aufrufen

Bei jedem Aufruf wird das Token im Kopf mitgeschickt:

Authorization: Bearer <access_token>

Soll in einem bestimmten Mandanten gearbeitet werden, wird dieser wie bei domizil+ selbst über den Kopf X-DPlus.Framework.Global.Company.Id angegeben.

Fehlermeldungen

Antwort	Bedeutung
400 unsupported_grant_type	Es wird nur client_credentials unterstützt
400 invalid_scope	Ein angeforderter Scope ist für den Client nicht erlaubt
401 invalid_client	Client-ID oder Secret falsch, Client deaktiviert oder abgelaufen, Benutzer gesperrt
429 temporarily_unavailable	Zu viele Fehlversuche, nach einigen Minuten erneut versuchen
401 invalid_token	Token abgelaufen, ungültig oder Client inzwischen deaktiviert – neues Token holen
403 insufficient_scope	Der Bereich ist für den Client nicht freigegeben oder für OAuth gesperrt

Einstellungen am Server

In der web.config des Servers (Haupt- und DMS-Server gleich):

Einstellung	Bedeutung
OAuth.TokenLifetimeMinutes	Gültigkeit der Tokens in Minuten (Standard 60, erlaubt 5 bis 120)
OAuth.Issuer	Aussteller im Token; Standard ist eine Kennung aus dem Lizenznehmer
OAuth.Audience	Empfänger im Token; Standard wie der Aussteller
OAuth.External.Authority	Optional: Adresse eines fremden Ausstellers (z. B. Microsoft Entra ID oder Keycloak), dessen Tokens ebenfalls angenommen werden
OAuth.External.Audience	Erwarteter Empfänger in den Tokens des fremden Ausstellers

Bei einem fremden Aussteller muss die Anwendung (z. B. die Application-ID der App-Registrierung in Entra ID) als OAuth-Client mit gleicher Client-ID in domizil+ angelegt sein. Benutzer und Scopes kommen von diesem Client.

Die Beschreibung des Servers für Standard-Bibliotheken steht unter /.well-known/openid-configuration, die öffentlichen Schlüssel unter framework/v1/oauth/jwks.